Skip to content

[drivers] Add mapping macros to map the top level api functions directly to the driver implementation#30

Merged
AlexLanzano merged 1 commit intowolfSSL:mainfrom
AlexLanzano:backends
Apr 17, 2026
Merged

[drivers] Add mapping macros to map the top level api functions directly to the driver implementation#30
AlexLanzano merged 1 commit intowolfSSL:mainfrom
AlexLanzano:backends

Conversation

@AlexLanzano
Copy link
Copy Markdown
Member

No description provided.

@AlexLanzano AlexLanzano self-assigned this Apr 17, 2026
Copilot AI review requested due to automatic review settings April 17, 2026 15:39
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR introduces “direct API mapping” so platform driver implementations can directly provide the top-level whal_<Type>_* symbols (bypassing vtables/dispatch), and updates board/platform macros and documentation accordingly.

Changes:

  • Add per-driver mapping flags that (1) rename driver functions to the top-level API at definition sites and (2) compile out unused vtables/prototypes when mapping is enabled.
  • Refactor platform “device” macros into separate _REGMAP and _DRIVER macros and update board initializers to match.
  • Add WHAL_ENOTIMPL and update docs/board Makefiles to compile the correct sources when mapping is enabled.

Reviewed changes

Copilot reviewed 98 out of 98 changed files in this pull request and generated 1 comment.

Show a summary per file
File Description
wolfHAL/watchdog/stm32wb_wwdg.h Guard watchdog driver prototypes/vtable decl when mapping is active
wolfHAL/watchdog/stm32wb_iwdg.h Guard watchdog driver prototypes/vtable decl when mapping is active
wolfHAL/uart/stm32wb_uart_dma.h Guard DMA-UART driver prototypes/vtable decl when mapping is active
wolfHAL/uart/stm32wb_uart.h Guard polled UART driver prototypes/vtable decl for mapping variants
wolfHAL/uart/stm32h5_uart.h Guard aliasing macros when mapping for STM32H5 is active
wolfHAL/uart/stm32f4_uart.h Guard STM32F4 UART prototypes/vtable decl when mapping is active
wolfHAL/uart/stm32c0_uart.h Guard aliasing macros when mapping for STM32C0 is active
wolfHAL/uart/pic32cz_uart.h Guard PIC32CZ UART prototypes/vtable decl when mapping is active
wolfHAL/timer/systick.h Add mapping guard and rename exported SysTick API to whal_SysTick_*
wolfHAL/supply/pic32cz_supc.h Guard PIC32CZ SUPC prototypes/vtable decl when mapping is active
wolfHAL/spi/stm32wb_spi.h Guard STM32WB SPI prototypes/vtable decl for mapping variants
wolfHAL/spi/stm32h5_spi.h Guard STM32H5 SPI prototypes/vtable decl when mapping is active
wolfHAL/spi/stm32f4_spi.h Guard STM32F4 SPI prototypes/vtable decl when mapping is active
wolfHAL/spi/stm32c0_spi.h Guard STM32C0 SPI aliasing macros when mapping is active
wolfHAL/sensor/imu/bmi270_sensor.h Guard BMI270 prototypes/vtable decl when mapping is active
wolfHAL/rng/stm32wb_rng.h Guard STM32WB RNG prototypes/vtable decl when mapping is active
wolfHAL/rng/stm32h5_rng.h Guard STM32H5 RNG prototypes/vtable decl when mapping is active
wolfHAL/platform/st/stm32wb55xx.h Split device macros into _REGMAP and _DRIVER macros
wolfHAL/platform/st/stm32h563xx.h Split device macros into _REGMAP and _DRIVER macros
wolfHAL/platform/st/stm32f411xx.h Split device macros into _REGMAP and _DRIVER macros
wolfHAL/platform/st/stm32c031xx.h Split device macros into _REGMAP and _DRIVER macros
wolfHAL/platform/microchip/pic32cz.h Split device macros into _REGMAP and _DRIVER macros
wolfHAL/platform/arm/cortex_m7.h Split SysTick device macro into _REGMAP and _DRIVER
wolfHAL/platform/arm/cortex_m4.h Split SysTick/NVIC device macros into _REGMAP and _DRIVER
wolfHAL/platform/arm/cortex_m33.h Split SysTick device macro into _REGMAP and _DRIVER
wolfHAL/platform/arm/cortex_m0plus.h Split SysTick device macro into _REGMAP and _DRIVER
wolfHAL/irq/cortex_m4_nvic.h Guard NVIC prototypes/vtable decl when mapping is active
wolfHAL/i2c/stm32wb_i2c.h Guard STM32WB I2C prototypes/vtable decl when mapping is active
wolfHAL/gpio/stm32wb_gpio.h Guard STM32WB GPIO prototypes/vtable decl for mapping variants
wolfHAL/gpio/stm32h5_gpio.h Guard GPIO aliasing macros when mapping for STM32H5 is active
wolfHAL/gpio/stm32f4_gpio.h Guard GPIO aliasing macros when mapping for STM32F4 is active
wolfHAL/gpio/stm32c0_gpio.h Guard GPIO aliasing macros when mapping for STM32C0 is active
wolfHAL/gpio/pic32cz_gpio.h Guard PIC32CZ GPIO prototypes/vtable decl when mapping is active
wolfHAL/flash/stm32wb_flash.h Guard STM32WB flash prototypes/vtable decl when mapping is active
wolfHAL/flash/stm32h5_flash.h Guard STM32H5 flash prototypes/vtable decl when mapping is active
wolfHAL/flash/stm32f4_flash.h Guard STM32F4 flash prototypes/vtable decl when mapping is active
wolfHAL/flash/stm32c0_flash.h Guard STM32C0 flash prototypes/vtable decl when mapping is active
wolfHAL/flash/spi_nor_flash.h Guard SPI-NOR top-level-like API prototypes; keep 4-byte init unguarded
wolfHAL/flash/pic32cz_flash.h Guard PIC32CZ flash prototypes/vtable decl when mapping is active
wolfHAL/eth_phy/lan8742a_eth_phy.h Guard LAN8742A PHY prototypes/vtable decl when mapping is active
wolfHAL/eth/stm32h5_eth.h Guard STM32H5 ETH prototypes/vtable decl when mapping is active
wolfHAL/error.h Add WHAL_ENOTIMPL error code
wolfHAL/dma/stm32wb_dma.h Guard STM32WB DMA prototypes/vtable decl when mapping is active
wolfHAL/crypto/stm32wb_aes.h Guard STM32WB AES prototypes/vtable decl when mapping is active
wolfHAL/clock/stm32wb_rcc.h Guard STM32WB RCC prototypes/vtable decl for PLL/MSI mapping variants
wolfHAL/clock/stm32h5_rcc.h Guard STM32H5 RCC prototypes/vtable decl for PLL/HSI mapping variants
wolfHAL/clock/stm32f4_rcc.h Guard STM32F4 RCC prototypes/vtable decl when mapping is active
wolfHAL/clock/stm32c0_rcc.h Guard STM32C0 RCC prototypes/vtable decl when mapping is active
wolfHAL/clock/pic32cz_clock.h Guard PIC32CZ clock prototypes/vtable decl when mapping is active
wolfHAL/block/sdhc_spi_block.h Guard SDHC-SPI block driver prototypes/vtable decl when mapping is active
src/watchdog/stm32wb_wwdg.c Add mapping rename block; compile out vtable when mapping is active
src/watchdog/stm32wb_iwdg.c Add mapping rename block; compile out vtable when mapping is active
src/uart/stm32wb_uart_dma.c Add mapping rename block; compile out vtable when mapping is active
src/uart/stm32wb_uart.c Add mapping rename block; add async stubs for mapped polled UART
src/uart/stm32f4_uart.c Add mapping rename block; add async not-impl stubs; compile out vtable when mapped
src/uart/pic32cz_uart.c Add mapping rename block; add async not-impl stubs; compile out vtable when mapped
src/timer/systick.c Add mapping rename block; rename SysTick_* to whal_SysTick_*; compile out vtable when mapped
src/supply/pic32cz_supc.c Add mapping rename block; compile out vtable when mapping is active
src/spi/stm32wb_spi.c Add mapping rename block; compile out vtable when mapping is active
src/spi/stm32h5_spi.c Add mapping rename block; compile out vtable when mapping is active
src/spi/stm32f4_spi.c Add mapping rename block; compile out vtable when mapping is active
src/sensor/imu/bmi270_sensor.c Add mapping rename block; compile out vtable when mapping is active
src/rng/stm32wb_rng.c Add mapping rename block; compile out vtable when mapping is active
src/rng/stm32h5_rng.c Add mapping rename block; compile out vtable when mapping is active
src/irq/cortex_m4_nvic.c Add mapping rename block; make functions non-static; compile out vtable when mapping is active
src/i2c/stm32wb_i2c.c Add mapping rename block; compile out vtable when mapping is active
src/gpio/stm32wb_gpio.c Add mapping rename block; compile out vtable when mapping is active
src/gpio/pic32cz_gpio.c Add mapping rename block; compile out vtable when mapping is active
src/flash/stm32wb_flash.c Add mapping rename block; compile out vtable when mapping is active
src/flash/stm32h5_flash.c Add mapping rename block; compile out vtable when mapping is active
src/flash/stm32f4_flash.c Add mapping rename block; compile out vtable when mapping is active
src/flash/stm32c0_flash.c Add mapping rename block; compile out vtable when mapping is active
src/flash/spi_nor_flash.c Add partial flash mapping rename block; compile out vtable when mapping is active
src/flash/pic32cz_flash.c Add mapping rename block; compile out vtable when mapping is active
src/eth_phy/lan8742a_eth_phy.c Add mapping rename block; compile out vtable when mapping is active
src/eth/stm32h5_eth.c Add mapping rename block; compile out vtable when mapping is active
src/dma/stm32wb_dma.c Add mapping rename block; make functions non-static; compile out vtable when mapping is active
src/crypto/stm32wb_aes.c Add mapping rename block; compile out vtable when mapping is active
src/crypto/crypto.c Compile out whal_Crypto_Init/Deinit wrappers when AES mapping is active
src/clock/stm32wb_rcc.c Add mapping rename blocks; compile out vtables when mapping is active
src/clock/stm32h5_rcc.c Add mapping rename blocks; compile out vtables when mapping is active
src/clock/stm32f4_rcc.c Add mapping rename block; compile out vtable when mapping is active
src/clock/stm32c0_rcc.c Add mapping rename block; compile out vtable when mapping is active
src/clock/pic32cz_clock.c Add mapping rename block; compile out vtable when mapping is active
src/block/sdhc_spi_block.c Add mapping rename block; compile out vtable when mapping is active
docs/writing_a_driver.md Document direct API mapping pattern and new platform macro conventions
docs/getting_started.md Document _REGMAP/_DRIVER macros and direct API mapping constraints
docs/adding_a_board.md Update guidance for mapping flags and dispatch source selection
boards/stm32wb55xx_nucleo/board.c Update device initializers to _REGMAP/_DRIVER and mapping-aware .driver usage
boards/stm32wb55xx_nucleo/Makefile.inc Enable mapping flags and adjust compiled sources to avoid symbol collisions
boards/stm32h563zi_nucleo/board.c Update device initializers to _REGMAP/_DRIVER and mapping-aware .driver usage
boards/stm32h563zi_nucleo/Makefile.inc Enable mapping flags and adjust compiled sources to avoid symbol collisions
boards/stm32f411_blackpill/board.c Update device initializers to _REGMAP/_DRIVER and mapping-aware .driver usage
boards/stm32f411_blackpill/Makefile.inc Enable mapping flags and adjust compiled sources to avoid symbol collisions
boards/stm32c031_nucleo/board.c Update device initializers to _REGMAP/_DRIVER and mapping-aware .driver usage
boards/stm32c031_nucleo/Makefile.inc Enable mapping flags and adjust compiled sources to avoid symbol collisions
boards/pic32cz_curiosity_ultra/board.c Update device initializers to _REGMAP/_DRIVER and mapping-aware .driver usage
boards/pic32cz_curiosity_ultra/Makefile.inc Enable mapping flags and adjust compiled sources to avoid symbol collisions
Comments suppressed due to low confidence (13)

wolfHAL/timer/systick.h:1

  • This changes the public header API from SysTick_* to whal_SysTick_* (the old symbols/prototypes are removed). If external users (or downstream boards) were calling SysTick_Init/Deinit/... directly, this is a breaking change. Consider adding compatibility aliases in the header (e.g., #define SysTick_Init whal_SysTick_Init, etc.) or retaining the old prototypes as deprecated wrappers to avoid breaking downstream code.
    wolfHAL/timer/systick.h:1
  • This changes the public header API from SysTick_* to whal_SysTick_* (the old symbols/prototypes are removed). If external users (or downstream boards) were calling SysTick_Init/Deinit/... directly, this is a breaking change. Consider adding compatibility aliases in the header (e.g., #define SysTick_Init whal_SysTick_Init, etc.) or retaining the old prototypes as deprecated wrappers to avoid breaking downstream code.
    wolfHAL/timer/systick.h:1
  • This changes the public header API from SysTick_* to whal_SysTick_* (the old symbols/prototypes are removed). If external users (or downstream boards) were calling SysTick_Init/Deinit/... directly, this is a breaking change. Consider adding compatibility aliases in the header (e.g., #define SysTick_Init whal_SysTick_Init, etc.) or retaining the old prototypes as deprecated wrappers to avoid breaking downstream code.
    wolfHAL/timer/systick.h:1
  • This changes the public header API from SysTick_* to whal_SysTick_* (the old symbols/prototypes are removed). If external users (or downstream boards) were calling SysTick_Init/Deinit/... directly, this is a breaking change. Consider adding compatibility aliases in the header (e.g., #define SysTick_Init whal_SysTick_Init, etc.) or retaining the old prototypes as deprecated wrappers to avoid breaking downstream code.
    wolfHAL/timer/systick.h:1
  • This changes the public header API from SysTick_* to whal_SysTick_* (the old symbols/prototypes are removed). If external users (or downstream boards) were calling SysTick_Init/Deinit/... directly, this is a breaking change. Consider adding compatibility aliases in the header (e.g., #define SysTick_Init whal_SysTick_Init, etc.) or retaining the old prototypes as deprecated wrappers to avoid breaking downstream code.
    src/irq/cortex_m4_nvic.c:1
  • These functions were changed from static to external unconditionally. If the project ever needs to compile/link multiple NVIC implementations (or otherwise wants to keep these internal when not mapping), this increases the chance of symbol collisions and expands the exported surface area. A more robust pattern is to keep these static when WHAL_CFG_IRQ_API_MAPPING_NVIC is not defined, and only make them external in the mapping configuration (e.g., via a WHAL_API/WHAL_LOCAL macro or #ifdef around the static).
    src/irq/cortex_m4_nvic.c:1
  • These functions were changed from static to external unconditionally. If the project ever needs to compile/link multiple NVIC implementations (or otherwise wants to keep these internal when not mapping), this increases the chance of symbol collisions and expands the exported surface area. A more robust pattern is to keep these static when WHAL_CFG_IRQ_API_MAPPING_NVIC is not defined, and only make them external in the mapping configuration (e.g., via a WHAL_API/WHAL_LOCAL macro or #ifdef around the static).
    src/irq/cortex_m4_nvic.c:1
  • These functions were changed from static to external unconditionally. If the project ever needs to compile/link multiple NVIC implementations (or otherwise wants to keep these internal when not mapping), this increases the chance of symbol collisions and expands the exported surface area. A more robust pattern is to keep these static when WHAL_CFG_IRQ_API_MAPPING_NVIC is not defined, and only make them external in the mapping configuration (e.g., via a WHAL_API/WHAL_LOCAL macro or #ifdef around the static).
    src/irq/cortex_m4_nvic.c:1
  • These functions were changed from static to external unconditionally. If the project ever needs to compile/link multiple NVIC implementations (or otherwise wants to keep these internal when not mapping), this increases the chance of symbol collisions and expands the exported surface area. A more robust pattern is to keep these static when WHAL_CFG_IRQ_API_MAPPING_NVIC is not defined, and only make them external in the mapping configuration (e.g., via a WHAL_API/WHAL_LOCAL macro or #ifdef around the static).
    wolfHAL/platform/st/stm32wb55xx.h:1
  • With direct API mapping enabled, many driver vtables are compiled out (e.g., whal_Stm32wbUart_Driver), but _DRIVER macros like this remain unconditionally defined and will expand to undefined symbols if accidentally used—leading to link-time failures that can be hard to diagnose. Consider making _DRIVER macros conditional on the corresponding mapping flag (or defining them to NULL / a sentinel and documenting it), so misuse is caught earlier and configurations are less error-prone.
    wolfHAL/uart/stm32wb_uart.h:1
  • The closing #endif comment doesn’t match the actual condition (it references WHAL_CFG_UART_API_MAPPING, but the guard is a multi-flag condition). Updating the comment to reflect the real condition would reduce confusion during maintenance/debugging.
    wolfHAL/uart/stm32wb_uart.h:1
  • The closing #endif comment doesn’t match the actual condition (it references WHAL_CFG_UART_API_MAPPING, but the guard is a multi-flag condition). Updating the comment to reflect the real condition would reduce confusion during maintenance/debugging.
    src/uart/stm32f4_uart.c:1
  • These async stubs are always compiled, even when WHAL_CFG_UART_API_MAPPING_STM32F4 is not enabled. In non-mapped builds, the generic dispatch likely determines async availability via vtable pointers, so these standalone functions can become dead/undocumented API surface. Consider wrapping these stubs in the same mapping guard used for renaming (like the STM32WB polled UART does), or explicitly documenting why they are intentionally exported even in non-mapped builds.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread src/flash/spi_nor_flash.c Outdated
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 98 out of 98 changed files in this pull request and generated 9 comments.


💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread src/uart/stm32wb_uart.c
Comment thread src/uart/stm32wb_uart.c
Comment thread wolfHAL/error.h
Comment thread docs/getting_started.md
Comment thread wolfHAL/uart/stm32wb_uart.h
Comment thread src/uart/stm32f4_uart.c
Comment thread src/uart/stm32f4_uart.c
Comment thread src/uart/pic32cz_uart.c
Comment thread src/uart/pic32cz_uart.c
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 100 out of 100 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (7)

wolfHAL/uart/uart.h:1

  • These comments state SendAsync/RecvAsync are NULL if unsupported, but several polled drivers in this PR populate these with stub functions that return WHAL_ENOTIMPL. Please align the contract: either (a) keep these pointers NULL in vtable-based builds and rely on the dispatch layer returning WHAL_ENOTIMPL, or (b) update the comment/API documentation to explicitly allow non-NULL stubs for unsupported async.
    src/uart/stm32wb_uart.c:1
  • The async stub functions are always compiled and wired into the vtable, even in non-mapped (vtable-dispatch) builds. This adds code size and contradicts the header comment that async pointers are NULL when unsupported. Recommendation: only compile these stubs (and assign them) when direct API mapping is enabled; otherwise set .SendAsync = NULL and .RecvAsync = NULL so the dispatch layer returns WHAL_ENOTIMPL without extra call overhead. This same pattern appears in other UART drivers added in this PR.
    src/uart/stm32wb_uart.c:1
  • The async stub functions are always compiled and wired into the vtable, even in non-mapped (vtable-dispatch) builds. This adds code size and contradicts the header comment that async pointers are NULL when unsupported. Recommendation: only compile these stubs (and assign them) when direct API mapping is enabled; otherwise set .SendAsync = NULL and .RecvAsync = NULL so the dispatch layer returns WHAL_ENOTIMPL without extra call overhead. This same pattern appears in other UART drivers added in this PR.
    wolfHAL/uart/stm32wb_uart.h:1
  • The #endif comment references WHAL_CFG_UART_API_MAPPING, but the guard condition checks several mapping macros. Please update the comment to match the actual condition (e.g., mention the specific macros or use a generic description like /* UART direct API mapping disabled */) to avoid confusion during future edits.
    wolfHAL/uart/stm32wb_uart.h:1
  • The #endif comment references WHAL_CFG_UART_API_MAPPING, but the guard condition checks several mapping macros. Please update the comment to match the actual condition (e.g., mention the specific macros or use a generic description like /* UART direct API mapping disabled */) to avoid confusion during future edits.
    wolfHAL/spi/stm32wb_spi.h:1
  • The #endif comment (!WHAL_CFG_SPI_API_MAPPING) doesn't match the actual condition (WHAL_CFG_SPI_API_MAPPING_STM32WB and WHAL_CFG_SPI_API_MAPPING_STM32C0). Update the comment so it reflects the real preprocessor guard.
    wolfHAL/spi/stm32wb_spi.h:1
  • The #endif comment (!WHAL_CFG_SPI_API_MAPPING) doesn't match the actual condition (WHAL_CFG_SPI_API_MAPPING_STM32WB and WHAL_CFG_SPI_API_MAPPING_STM32C0). Update the comment so it reflects the real preprocessor guard.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@AlexLanzano AlexLanzano merged commit a1823e3 into wolfSSL:main Apr 17, 2026
18 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants